Python-pakettien jakelu: PyPI-julkaisu ja versionhallinta

Pythonin laaja ekosysteemi perustuu valtavaan pakettien kokoelmaan, joka on helposti saatavilla Python Package Indexin (PyPI) kautta. Tämä opas tarjoaa kattavan yleiskatsauksen siitä, kuinka voit jakaa omia Python-pakettejasi PyPI:n kautta varmistaen, että ne ovat kehittäjien saatavilla maailmanlaajuisesti. Käymme läpi olennaiset työkalut, versionhallinnan parhaat käytännöt sekä työnkulut laadukkaiden Python-pakettien luomiseen ja julkaisemiseen.

Miksi jakaa oma Python-paketti?

Python-paketin jakelu tarjoaa lukuisia etuja:

• Työsi jakaminen: Mahdollistaa muiden kehittäjien helpon koodisi uudelleenkäytön, edistäen yhteistyötä ja innovaatiota. Kuvittele maailmanlaajuinen tiimi käyttämässä sinun erikoistuneita Pythonilla rakennettuja data-analyysityökalujasi.
• Riippuvuuksien hallinta: Yksinkertaistaa riippuvuuksien hallintaa muissa projekteissa. Pakettisi voidaan asentaa yhdellä komennolla kaikkine riippuvuuksineen.
• Avoimen lähdekoodin edistäminen: Mahdollistaa osallistumisesi avoimen lähdekoodin yhteisöön ja tunnustuksen saamisen työstäsi. Monet kriittiset ohjelmistokomponentit ovat avoimen lähdekoodin paketteja, joita ylläpitävät kehittäjät maailmanlaajuisesti.
• Versionhallinta ja päivitykset: Tarjoaa jäsennellyn tavan hallita versioita, julkaista päivityksiä ja korjata virheitä. Tämä varmistaa, että käyttäjillä on aina pääsy pakettisi uusimpaan ja luotettavimpaan versioon.
• Helppo asennus: Yksinkertaistaa asennusta käyttäjille komennolla `pip install sinun-paketin-nimi`.

Olennaiset työkalut Python-pakettien jakeluun

Useat työkalut ovat välttämättömiä Python-pakettien luomisessa ja jakelussa:

• setuptools: Laajalti käytetty kirjasto paketin metatietojen, kuten nimen, version, riippuvuuksien ja sisääntulopisteiden (entry points), määrittelyyn. Se on de facto -standardi Python-projektien paketoinnissa.
• wheel: Jakelumuoto, joka tarjoaa tehokkaamman ja luotettavamman asennusprosessin lähdekoodijakeluihin verrattuna. Wheelit ovat esikäännettyjä jakeluita, jotka voidaan asentaa ilman kääntämistä.
• twine: Työkalu paketin turvalliseen lataamiseen PyPI:hin. Twine salaa tunnuksesi ja paketin datan siirron aikana, suojaten salakuuntelulta ja väliintulohyökkäyksiltä.
• venv/virtualenv: Nämä ovat työkaluja eristettyjen Python-ympäristöjen luomiseen. Virtuaaliympäristöjen käyttö on ratkaisevan tärkeää riippuvuuksien hallinnassa ja eri projektien välisten konfliktien välttämisessä.

Projektin pystyttäminen

Ennen kuin voit jakaa pakettisi, sinun on rakennettava projektisi oikein.

Esimerkki projektirakenteesta

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Selitys:

• my_package/: Pääkansio, joka sisältää pakettisi lähdekoodin.
• my_package/__init__.py: Tekee `my_package`-kansiosta Python-paketin. Se voi olla tyhjä tai sisältää alustuskoodia.
• my_package/module1.py, my_package/module2.py: Python-moduulisi, jotka sisältävät varsinaisen koodin.
• tests/: Kansio, joka sisältää yksikkötestisi. On ratkaisevan tärkeää kirjoittaa testejä pakettisi laadun ja luotettavuuden varmistamiseksi.
• README.md: Markdown-tiedosto, joka sisältää kuvauksen paketistasi, käyttöohjeet ja muuta oleellista tietoa. Tämä on usein ensimmäinen asia, jonka käyttäjät näkevät PyPI:ssä.
• LICENSE: Tiedosto, joka sisältää lisenssin, jolla pakettisi jaetaan (esim. MIT, Apache 2.0, GPL). Sopivan lisenssin valitseminen on olennaista määriteltäessä, miten muut voivat käyttää koodiasi.
• setup.py: Pääkonfiguraatiotiedosto, joka määrittelee pakettisi metatiedot ja käännösohjeet.
• .gitignore: Määrittää tiedostot ja kansiot, jotka Gitin tulisi jättää huomiotta (esim. väliaikaistiedostot, käännösartefaktit).

Tiedoston `setup.py` luominen

`setup.py`-tiedosto on pakettisi jakelun ydin. Se sisältää metatietoja paketistasi sekä ohjeet sen kääntämiseen ja asentamiseen. Tässä on esimerkki:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Korvaa pakettisi nimellä
    version="0.1.0",
    author="Oma Nimi",  # Korvaa nimelläsi
    author_email="oma.sahkoposti@example.com", # Korvaa sähköpostillasi
    description="Pieni esimerkkipaketti",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/omakayttaja/my_package", # Korvaa arkistosi URL-osoitteella
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Esimerkkiriippuvuus
    ],
)

Selitys:

• name: Pakettisi nimi, jota käytetään PyPI:ssä. Valitse yksilöllinen ja kuvaava nimi.
• version: Pakettisi versionumero. Noudata semanttista versiointia (katso alla).
• author, author_email: Nimesi ja sähköpostiosoitteesi.
• description: Lyhyt kuvaus paketistasi.
• long_description: Pidempi, yksityiskohtaisempi kuvaus, joka tyypillisesti luetaan `README.md`-tiedostostasi.
• long_description_content_type: Määrittää pitkän kuvauksesi muodon (esim. "text/markdown").
• url: Pakettisi kotisivun URL-osoite (esim. GitHub-arkisto).
• packages: Luettelo paketeista, jotka sisällytetään jakeluusi. `setuptools.find_packages()` löytää automaattisesti kaikki projektisi paketit.
• classifiers: Metatietoja, jotka auttavat käyttäjiä löytämään pakettisi PyPI:stä. Valitse sopivat luokittimet Trove Classifiers -luettelosta. Harkitse luokittimien lisäämistä tuetuille Python-versioille, käyttöjärjestelmille ja lisensseille.
• python_requires: Määrittää vähimmäis-Python-version, jota pakettisi käyttö edellyttää.
• install_requires: Luettelo riippuvuuksista, joita pakettisi vaatii. Nämä riippuvuudet asennetaan automaattisesti, kun pakettisi asennetaan.

Versionhallinta: Semanttinen versiointi

Semanttinen versiointi (SemVer) on laajalti omaksuttu versiointijärjestelmä, joka tarjoaa selkeän ja johdonmukaisen tavan viestiä pakettisi muutosten luonteesta.

SemVer-versionumero koostuu kolmesta osasta: `PÄÄ.SIVU.PAIKKAUS` (MAJOR.MINOR.PATCH).

• PÄÄ (MAJOR): Kasvatetaan, kun teet yhteensopimattomia API-muutoksia. Tämä osoittaa merkittävän muutoksen, joka saattaa vaatia käyttäjiä päivittämään koodinsa.
• SIVU (MINOR): Kasvatetaan, kun lisäät toiminnallisuutta taaksepäin yhteensopivalla tavalla. Tämä merkitsee uusia ominaisuuksia tai parannuksia, jotka eivät riko olemassa olevaa koodia.
• PAIKKAUS (PATCH): Kasvatetaan, kun teet taaksepäin yhteensopivia virheenkorjauksia. Tämä on tarkoitettu pienille korjauksille, jotka eivät lisää uusia ominaisuuksia tai riko olemassa olevaa toiminnallisuutta.

Esimerkkejä:

• 1.0.0: Ensimmäinen julkaisu.
• 1.1.0: Lisätty uusi ominaisuus rikkomatta olemassa olevaa koodia.
• 1.0.1: Korjattu virhe 1.0.0-julkaisussa.
• 2.0.0: Tehty yhteensopimattomia API-muutoksia.

SemVerin käyttö auttaa käyttäjiä ymmärtämään pakettisi uuteen versioon päivittämisen vaikutukset.

Paketin kääntäminen

Kun `setup.py`-tiedostosi on määritetty, voit kääntää pakettisi.

1. Luo virtuaaliympäristö: On erittäin suositeltavaa luoda virtuaaliympäristö pakettisi riippuvuuksien eristämiseksi. Käytä `python3 -m venv .venv` (tai `virtualenv .venv`) ja aktivoi se sitten (`source .venv/bin/activate` Linuxilla/macOS:llä, `.venv\Scripts\activate` Windowsilla).
2. Asenna kääntämisriippuvuudet: Suorita `pip install --upgrade setuptools wheel`.
3. Käännä paketti: Suorita `python setup.py sdist bdist_wheel`. Tämä komento luo kaksi jakelutiedostoa `dist`-kansioon: lähdekoodijakelun (sdist) ja wheel-jakelun (bdist_wheel).

`sdist` sisältää lähdekoodisi ja `setup.py`-tiedoston. `bdist_wheel` on esikäännetty jakelu, joka voidaan asentaa nopeammin.

Paketin julkaiseminen PyPI:hin

Ennen kuin voit julkaista pakettisi, sinun on luotava tili PyPI:hin (https://pypi.org/) ja luotava API-avain. Tätä avainta käytetään lataustesi todentamiseen.

1. Rekisteröidy PyPI:hin: Mene osoitteeseen https://pypi.org/account/register/ ja luo tili.
2. Luo API-avain: Mene osoitteeseen https://pypi.org/manage/account/, vieritä alas "API tokens" -osioon ja luo uusi avain. Säilytä tämä avain turvallisesti, sillä tarvitset sitä pakettisi lataamiseen.
3. Asenna Twine: Suorita `pip install twine`.
4. Lataa pakettisi: Suorita `twine upload dist/*`. Sinulta kysytään käyttäjätunnusta (`__token__`) ja salasanaa (luomasi API-avain).

Tärkeä turvallisuushuomautus: Älä koskaan committaa API-avaintasi arkistoosi. Säilytä se turvallisesti ja käytä ympäristömuuttujia tai muita turvallisia menetelmiä sen käyttämiseen latausprosessin aikana.

Paketin asennuksen testaaminen

Paketin julkaisemisen jälkeen on olennaista testata, että se voidaan asentaa oikein.

1. Luo uusi virtuaaliympäristö: Tämä varmistaa, että testaat asennusta puhtaassa ympäristössä.
2. Asenna pakettisi: Suorita `pip install sinun-paketin-nimi`.
3. Tuo ja käytä pakettiasi: Tuo pakettisi Python-tulkissa ja varmista, että se toimii odotetusti.

Jatkuva integraatio ja jatkuva käyttöönotto (CI/CD)

Automatisoidaksesi paketin kääntämis-, testaus- ja julkaisuprosessia voit käyttää CI/CD-työkaluja, kuten GitHub Actions, GitLab CI tai Travis CI.

Tässä on esimerkki GitHub Actions -työnkulusta, joka kääntää ja julkaisee pakettisi PyPI:hin:

name: Julkaise PyPI:hin

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Selitys:

• Tämä työnkulku käynnistyy, kun uusi julkaisu (release) julkaistaan GitHubissa.
• Se hakee koodin, asentaa Pythonin, asentaa riippuvuudet, kääntää paketin ja lataa sen PyPI:hin.
• secrets.PYPI_API_TOKEN on GitHub-salaisuus (secret), joka tallentaa PyPI API-avaimesi. Sinun on määritettävä tämä salaisuus GitHub-arkistosi asetuksissa.

Parhaat käytännöt Python-pakettien jakelussa

• Kirjoita kattava dokumentaatio: Sisällytä yksityiskohtainen `README.md`-tiedosto sekä API-dokumentaatio käyttämällä työkaluja kuten Sphinx. Selkeä ja täydellinen dokumentaatio on ratkaisevan tärkeää, jotta pakettisi on helppokäyttöinen.
• Kirjoita yksikkötestejä: Testaa koodisi perusteellisesti sen laadun ja luotettavuuden varmistamiseksi. Käytä testauskehystä, kuten pytest tai unittest.
• Noudata PEP 8 -tyyliohjeita: Noudata Python Enhancement Proposal 8 (PEP 8) -tyyliopasta varmistaaksesi yhtenäisen ja luettavan koodin.
• Käytä lisenssiä: Valitse sopiva avoimen lähdekoodin lisenssi määrittääksesi, miten muut voivat käyttää koodiasi.
• Pidä riippuvuutesi ajan tasalla: Päivitä säännöllisesti pakettisi riippuvuudet hyötyäksesi virheenkorjauksista, tietoturvakorjauksista ja uusista ominaisuuksista.
• Käytä virtuaaliympäristöä: Kehitä ja testaa pakettiasi aina virtuaaliympäristössä riippuvuuksien eristämiseksi.
• Harkitse kansainvälistämistä (i18n) ja lokalisointia (l10n): Jos pakettisi käsittelee käyttäjälle näkyvää tekstiä tai dataa, harkitse sen mukauttamista eri kielille ja alueille. Tämä laajentaa potentiaalista käyttäjäkuntaasi maailmanlaajuisesti. Työkalut, kuten Babel, voivat auttaa tässä.
• Käsittele eri aikavyöhykkeitä ja valuuttoja: Jos pakettisi käsittelee päivämääriä, aikoja tai rahansiirtoja, ota huomioon eri aikavyöhykkeet ja valuutat ympäri maailmaa. Käytä sopivia kirjastoja ja API-rajapintoja näiden monimutkaisuuksien oikeaan käsittelyyn.
• Tarjoa selkeitä virheilmoituksia: Kirjoita informatiivisia virheilmoituksia, jotka auttavat käyttäjiä ymmärtämään, mikä meni vikaan ja kuinka korjata se. Käännä nämä virheilmoitukset eri kielille, jos mahdollista.
• Mieti saavutettavuutta: Ota huomioon vammaiset käyttäjät suunnitellessasi pakettisi käyttöliittymää ja dokumentaatiota. Noudata saavutettavuusohjeita varmistaaksesi, että pakettisi on kaikkien käytettävissä.

Edistyneet aiheet

• Nimiavaruuspaketit (Namespace packages): Mahdollistavat yhden Python-paketin jakamisen useisiin hakemistoihin tai jopa useisiin jakeluihin.
• Sisääntulopisteet (Entry points): Mahdollistavat funktioiden tai luokkien määrittelyn, joita voidaan kutsua muista paketeista tai komentoriviltä.
• Datatiedostot: Mahdollistavat muiden kuin Python-tiedostojen (esim. datatiedostot, konfiguraatiotiedostot) sisällyttämisen jakeluusi.
• Ehdolliset riippuvuudet: Mahdollistavat riippuvuuksien määrittelyn, jotka vaaditaan vain tietyissä olosuhteissa (esim. tietyssä käyttöjärjestelmässä).

Yhteenveto

Python-paketin jakelu PyPI:ssä on loistava tapa jakaa työsi maailman kanssa ja osallistua Python-ekosysteemin kehittämiseen. Noudattamalla tässä oppaassa esitettyjä vaiheita ja parhaita käytäntöjä voit luoda ja julkaista laadukkaita Python-paketteja, jotka ovat helppoja asentaa, käyttää ja ylläpitää. Muista painottaa selkeää dokumentaatiota, perusteellista testausta ja johdonmukaista versionhallintaa varmistaaksesi pakettisi menestyksen.